Creates a catalog iterator that can be used to iterate over the contents of a directory or volume.

OSErr FSOpenIterator (
    const FSRef *container, 
    FSIteratorFlags iteratorFlags, 
    FSIterator *iterator
);

container

A pointer to an FSRef for the directory to iterate (or the root of the subtree to iterate).

The set of items to iterate over can either be the objects directly contained in a directory, or all items directly or indirectly contained in a directory (i.e. recursive or subtree).

iteratorFlags

A set of flags which controls whether the iterator iterates over subtrees or just the immediate children of the container. At this time, only one bit (bit 0) is defined. If the bit is clear (i.e. kFSIterateFlat is passed), then the set of items to iterate over is the set of files and folders directly contained by the container directory; that is, the files and folders whose parent directory is container. If the bit is set (i.e. kFSIterateSubtree is passed), then the set of items are all files and folders directly or indirectly contained by container; that is, files or folders in the subtree rooted at container.

iterator

On return, a pointer to the new FSIterator. The iterator is automatically initialized so that the next use of the iterator returns the first item. The order that items are returned in is volume format dependent and may be different for two different iterators created with the same container and flags.

Catalog iterators must be closed when you are done using them, whether or not you have iterated over all the items. Iterators are automatically closed upon process termination (just like open files). However, you should use the FSCloseIterator call to close an iterator to free up any system resources allocated to the iterator.

function result

A result code.

AVAILABILITY

Supported in Carbon. Available in Mac OS 9, and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)